About Page Formatting(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / About Page Formatting and Dialog Box Customization

About Page Formatting
Page formatting allows the user to format specific pages of a document differently from the default formatting for the rest of the document. Using QuickDraw GX page formatting features, your application can

allow users to specify unique formats for the individual pages of a document
retrieve a format object's mapping
attach a form to a format object as a backdrop to each page
create documents that contain page-specific halftone information
copy a format object for use in other documents

For example, using page-formatting features, a mail-merge application may automatically generate a document in which the first page consists of a template in which a user can enter addresses and the rest of the document consists of blank sheets in which a user can add text.
Figure 3-4 shows a document that is composed of a two-page letter and many address labels. The job object references two format objects, one for either page of the letter and the other for the address label.
Figure 3-4 A three page document and its corresponding job and format objects

Manipulating format objects is described in the next section. Information on accessing a format object's mapping is discussed in "Mapping for Format Objects" beginning on page 3-18. Information on attaching a form to a format object is discussed in "Forms and Format Objects" beginning on page 3-20. Information on halftones is discussed in "Halftones and Format Collections" beginning on page 3-21.

Manipulating Format Objects
A format object contains the basic information that your application needs to display a single page or a set of pages. Generally, you work with format objects when a user

creates a new format using the Custom Page Setup dialog box
wants to use a format in several pages of a document
modifies a format that is shared by other pages in the same document
saves or opens a document

Figure 3-5 shows how you manipulate format objects in response to the first three actions.
Figure 3-5 Manipulating the format object in response to user actions

When a user creates a new format through the Custom Page Setup dialog box, you need to create a new format object. Creating a new format object is discussed in "Creating a Format Object for a Page in a Document," which begins on page 3-40.
Each format object you create has an associated owner count. The owner count indicates the number of times that a format object is shared. When a user creates a new format through the Custom Page Setup dialog box, you need to create a new format object with the GXNewFormat function. This function sets the owner count of a format object to 1.
When a user wants to use the new format to format another page the same way, you need to increment the format object's owner count. You use the GXCloneFormat function to increment the owner count of a format object by 1. Cloning a format object is discussed in "Sharing Formats for Document Pages," which begins on page 3-44.
When a user modifies a format object that is also shared by other pages, you need to dispose of its corresponding format object and create a new one. The GXDisposeFormat function decrements the owner count of a format object by 1. Disposing of a format object is discussed in "Disposing of a Format Object for a Page in a Document," which begins on page 3-47.
To obtain the current owner count of a format object, you use the GXCountFormatOwners function. For more information about this function, see the description of GXCountFormatOwners on page 3-107.
You also must create a correspondence between the format and the page. Typically, you keep the correspondence in the format collection. You must save the correspondences when the job is flattened and retrieve them when the job is unflattened. For an example, see "Associating Format Objects With Document Pages" beginning on page 3-61.

Mapping for Format Objects
A format object's mapping is a mathematical representation of the format object's settings. These settings include the paper size, page size, orientation, and scaling. The paper size and page size are set when you create the format object.
QuickDraw GX uses this mapping to scale page information into device pixels. A device pixel is the smallest physical area that a printer is capable of rendering. Typically, the mapping consists of the high-resolution scaling information needed to print a page at the highest quality.
QuickDraw GX and the printer driver set up the mapping. Your application can retrieve the mapping but cannot set it directly. You might want to retrieve it, for example, to set the mapping property of a view port to represent the printer on screen. For more information about view port objects, see the view-related objects chapter of Inside Macintosh: QuickDraw GX Objects.
Figure 3-6 shows how the scaling item affects the mapping.
Figure 3-6 Scaling a format object

When 50% scaling is applied, the scaling variables in the mapping are actually doubled, which causes the shape to appear the same size on a page of paper that is twice its original size. When the printer driver maps the page to dots-per-inch, it reduces the format dimension and everything within them, including the shape object. The result is that the shape is scaled to 50% when it is printed.

Forms and Format Objects
QuickDraw GX provides the form property, which allows your application to format pages of a document with a template. A form is made up of two shape objects--one shape defines the form itself, and the other shape, the mask shape, defines erasable areas within the form. The mask shape is optional; your application can erase the contents within a form, but this technique is not recommended.
Your application can specify a form for any format object associated with the formatting printer. Your application uses this form as a backdrop that is applied to a set of pages. For example, you can use a form to define erasable areas within pages created using a database application.
To associate a form shape and a mask shape with a format object associated with a page, you use the GXSetFormatForm function. To retrieve the form and mask shapes for a particular format object, you use the GXGetFormatForm function. The shape type that you associate with a format object must be a picture shape.
Figure 3-7 shows a page from a document created by a database application. The figure also shows the job object corresponding to the document, the job's format object, and a form.
Figure 3-7 Using a form to format a page

Forms save time during spooling, rendering, and I/O. During spooling, QuickDraw GX spools a form shape only once. QuickDraw GX renders a form shape once for each distinct format object it is attached to. During I/O, if the printer can cache the representation of the form, QuickDraw GX saves data transmission time by sending the form to the printer only when it has to.

Halftones and Format Collections
You can use a halftone to represent more colors than can be represented on a printer by alternating available colors of a fixed cell size so that a noncontinuous tone device appears to produce continuous-tone grayscale or full-color images.
You can use the format collection to specify halftone information on a page-by-page basis. Initially, the printer driver specifies the halftone information for the default format by storing the information in this format's format collection object. You can add halftones to this collection, in which case you are changing the halftone for the entire document. You can also change the halftone information in a format collection associated with the format object for specific pages, in which case only the pages associated with the format object receive the halftone. Storing halftone information in a format collection is discussed in "Storing Halftone Information in a Format Collection," which begins on page 3-52.

Note
To specify halftone information on a shape-by-shape basis, you use a synonym attached to the shape's ink object. For more information about the halftone synonym, see the chapter "Advanced Printing Features" in this book.
The format-halftone item in the format collection specifies the halftones to use. The collection item specifies a gxFormatHalftoneInfo structure that defines the number of allowable halftones and their characteristics. For the definition of the gxFormatHalftoneInfo structure, see "Format-Halftone Information" on page 3-92.
The definition of each halftone is specified in a gxHalftone structure, which is described completely in the view-related objects chapter of Inside Macintosh: QuickDraw GX Objects:
struct gxHalftone{
   fixed          angle;            /* direction of halftone */
   fixed          frequency;        /* cells per inch */
   gxDotType      method;           /* kind of pattern */
   gxTintType     tinting;          /* tint calculation method */
   gxColor        dotColor;         /* color of foreground */
   gxColor        backgroundColor;  /* color of background */
   gxColorSpace   tintSpace;        /* color space for tint */
};
You can specify any number of these gxHalftone structures in the format-halftone information item. QuickDraw GX selects appropriate halftones from the list of available halftones in the item. Its selection is based upon the tinting field in the halftone structure:

When you print to a black-and-white PostScript device, QuickDraw GX looks for a halftone structure that specifies gxLuminanceTint in the tinting field. If no halftone specifies this value, it looks for a halftone that specifies gxComponent4Tint as its tinting method. Component 4 is the black component in the CMYK (cyan, magenta, yellow, and black) space. If no halftone specifies this tinting method either, the first halftone in the list is used.
When you print to a color PostScript device, a maximum of four halftones are used. QuickDraw GX attempts to locate halftones for the following tint calculation methods: gxComponent1Tint for the cyan halftone, gxComponent2Tint for the magenta halftone, gxComponent3Tint field for the yellow halftone, and gxComponent4Tint for the black halftone. If a tinting method is in the list more than once, the first one in the list is used.
If a halftone for the gxComponent4Tint method is not in the list, QuickDraw GX uses the gxLuminanceTint tinting method for the black halftone. If the gxLuminanceTint tinting method cannot be found either, QuickDraw GX uses the first halftone in the list for the black halftone.
If QuickDraw GX cannot find a halftone for the gxComponent1Tint, gxComponent2Tint, or gxComponent3Tint tinting methods, it uses the black halftone for the missing tinting method.

It is only possible to use halftones to the extent that a particular PostScript device supports them. The dot color and background color of a halftone are ignored because QuickDraw GX assumes that the dot color for a black-and-white device is black and the dot color for a color device with the gxComponent2Tint tinting method is magenta.